Einheit 9 — Debuggen: Logs, Messages, Re-Emit

Was du nach dieser Einheit weißt: Du verfolgst den Weg einer Nachricht durch den gesamten Workflow, findest den Agent, an dem sie stehenbleibt, und lässt dieselbe echte Payload beliebig oft erneut durchlaufen.

Logs und Messages sind zwei verschiedene Dinge

Das ist die wichtigste Unterscheidung dieser Einheit — und die, die Anfänger am meisten Zeit kostet.

	Messages	Logs
Zeigen	Was ein Agent ausgegeben hat	Was ein Agent getan hat
Antworten auf	„Welche Daten kamen raus?"	„Warum kam nichts raus?"
Werkzeuge	`workflow_messages`, `agent_messages`	`workflow_logs`, `agent_logs`

Wenn ein Agent keine Nachricht erzeugt hat, steht der Grund im Log — nicht in den Messages. Und wenn eine Nachricht falsche Daten enthält, siehst du das in den Messages, nicht im Log.

`workflow_messages` — der Datenfluss

Ohne weitere Angabe liefert es die Nachrichten der letzten Ausführung:

{
  "execution": {
    "id": 231639,
    "workflow_run_id": "0b1abc97-c4ae-4483-b736-695d3375805f",
    "started_at": "2026-09-19T15:36:16+02:00",
    "finished_at": "2026-09-19T15:37:14+02:00",
    "error": false,
    "status": "completed"
  },
  "messages": [ … ]
}

Der execution-Block allein beantwortet schon viel: Lief es durch? Gab es einen Fehler? Wie lange hat es gedauert?

Mit agent_id filterst du auf einen Agent, mit execution_id auf einen bestimmten Lauf.

`agent_messages` — was dieser Agent ausgegeben hat

{
  "id": 29214,
  "agent_id": 1901,
  "agent_name": "extrahieren",
  "payload": {
    "name": "Dr. Anke Reinhardt",
    "company": "Nordwerk Präzisionstechnik GmbH",
    "email": "a.reinhardt@nordwerk-pt.example",
    "last_message": {
      "freitext": "Hallo zusammen, …"
    },
    "workflow_run_id": "0b1abc97-…",
    "trace_id": "d6f4b382-…"
  }
}

Hier siehst du auf einen Blick:

Die KI hat die drei Felder oben abgelegt — das bewirkt output_format: "json"
Die eingehende Payload ist unter last_message erhalten geblieben
workflow_run_id und trace_id verknüpfen die Nachricht mit dem Lauf

Das ist zugleich die beste Quelle für Testpayloads (Einheit 7): echte Daten statt erfundener.

`agent_logs` — warum dieser Agent das getan hat

Der Generative AI Agent protokolliert erfreulich ausführlich:

GenAiAgent: Eingehende Payload: {"freitext":"Hallo zusammen, …"}
GenAiAgent: Aktive Optionen: model=gus:tav timeout=120 output_format=json
LLM-Token aus Cache verwendet.
Prompt nach 1 Iteration(en) fertig gerendert: Extrahiere den Absender …
Rendered Prompt: Extrahiere den Absender aus dem folgenden E-Mail-Text. …
Generation completed.
propagated

Drei Zeilen davon sind Gold wert:

Zeile	Beantwortet
`Eingehende Payload`	Kam überhaupt an, was du erwartet hast?
`Aktive Optionen`	Ist die Option wirklich gesetzt, die du gesetzt zu haben glaubst?
`Rendered Prompt`	Was hat das Modell tatsächlich gelesen, nach dem Liquid-Rendern?

Der gerenderte Prompt löst die meisten KI-Probleme

Wenn eine KI-Auswertung Unsinn liefert, liegt es selten am Modell. Meistens steht im gerenderten Prompt ein leerer Platzhalter, weil der Liquid-Pfad nicht stimmt — {{ freitext }} statt {{ last_message.freitext }} oder umgekehrt.

Schau dir immer zuerst Rendered Prompt an, bevor du am Prompt-Text feilst.

Beim Post Agent steht der komplette Request im Log:

Preparing POST request to https://…/contacts
headers: {"Content-Type" => "application/json; charset=utf-8"}
Sending request ...
Full request: {method: "POST", url: "https://…/contacts", …,
  body: "{\"company\":\"Nordwerk Präzisionstechnik GmbH\",
          \"email\":\"a.reinhardt@nordwerk-pt.example\",
          \"name\":\"Dr. Anke Reinhardt\"}"}
Received response status 201

Ziel, Header, gerenderter Body, Antwortcode — mehr braucht man für einen HTTP-Fehler nicht.

Log-Level

min_level filtert nach Ausführlichkeit. min_level: 3 liefert die detaillierten Einträge, niedrigere Level sind knapper (Level 1 ist zum Beispiel das schlichte propagated, wenn eine Nachricht weitergereicht wurde). Fang bei 3 an, wenn du etwas suchst.

`message_reemit` — nochmal, mit denselben Daten

Der beste Testfall ist der Fall, der schiefgegangen ist. message_reemit schickt eine bestehende Nachricht als neue Nachricht am selben Agent erneut los:

{
  "success": true,
  "message": "Message 29213 re-emitted as 29215"
}

Damit läuft die Kette ab diesem Agent komplett neu durch — mit exakt denselben Daten wie beim Fehlschlag.

Die typische Reparaturschleife:

workflow_messages   → welche Nachricht ist die letzte vor dem Abriss?
agent_logs          → warum ging es dort nicht weiter?
agent_update        → Konfiguration korrigieren
message_reemit      → dieselbe Nachricht nochmal durchschicken
agent_messages      → hat es jetzt geklappt?

Das ersetzt das Nachstellen von Hand: kein Formular neu ausfüllen, keine Test-E-Mail neu schicken.

Re-Emit löst echte Aktionen aus

Die Nachricht läuft durch den kompletten nachgelagerten Teil des Workflows. Schreibt der in ein Zielsystem, wird dort erneut geschrieben — beim dritten Re-Emit liegen drei Datensätze da.

Deaktiviere schreibende Agents vorübergehend (agent_update mit disabled: true), wenn du nur den vorderen Teil prüfen willst.

📹 Video: [Platzhalter — Screencast: Kompletter Debug-Durchlauf von der Fehlermeldung bis zum erfolgreichen Re-Emit]

Ein Ablauf, der fast immer funktioniert

Das Symptom ist meistens dasselbe: „Am Ende kommt nichts an."

workflow_messages — wo bricht die Kette ab? Suche den letzten Agent, der noch eine Nachricht erzeugt hat.
agent_logs auf den Agent danach — der hat entweder gar nicht ausgelöst oder ist gescheitert. Der Grund steht dort.
Ursache einordnen:
- Nichts im Log, keine Nachricht → der Agent ist gar nicht verbunden. Zurück zu workflow_show und Einheit 6.
- Log da, aber Payload unerwartet → der Liquid-Pfad stimmt nicht. Vergleiche mit der echten Nachricht des Vorgängers.
- Log da, HTTP-Fehler → Request-Aufbau prüfen, Full request lesen.
- filter-Agent hat nichts durchgelassen → die Regel greift nicht wie gedacht.
Korrigieren mit agent_update (einzelner Agent) oder workflow_update (Struktur).
message_reemit und ab Schritt 1 nachkontrollieren.

Zusammengefasst

Frage	Werkzeug
Ist der Lauf durchgelaufen?	`workflow_messages` → `execution.status`
Wo bricht die Kette ab?	`workflow_messages` über alle Agents
Welche Daten kamen aus Agent X?	`agent_messages`
Warum hat Agent X nichts getan?	`agent_logs` mit `min_level: 3`
Was hat die KI wirklich gelesen?	`agent_logs` → `Rendered Prompt`
Was wurde wirklich gesendet?	`agent_logs` → `Full request`
Nochmal mit denselben Daten	`message_reemit`

Weiter: Einheit 10 — Ändern ohne kaputtmachen

Logs und Messages sind zwei verschiedene Dinge​

workflow_messages — der Datenfluss​

agent_messages — was dieser Agent ausgegeben hat​

agent_logs — warum dieser Agent das getan hat​

Log-Level​

message_reemit — nochmal, mit denselben Daten​

Ein Ablauf, der fast immer funktioniert​

Zusammengefasst​